\section Introduction

\grok\ was born as ``grok'', but the name was changed later to this
more descriptive variation. It is a simple desktop database manager,
intended to manage small databases such as phone lists, diaries, todo
lists, URL lists, etc. A user interface builder is integrated in
\grok\ to allow customization of the presentation of the data in the
main window. A variety of user interface elements such as text entry
fields, checkbuttons, function buttons, and bar charts ca be placed
in the database-dependent part of the main window, called the {\it
card}. \grok\ comes with a selection of pre-built applications.

The database itself is organized in a table with rows and columns of
strings. A {\it card} presents one row of the database. For example,
the phone list stores one person per row, with various columns for
name, address, phone number, and so on.

In addition top the card, the main window also displays a scrollable
{\it summary} listing containing one line per card, allowing fast
lookup of cards. Pressing on a line in the summary puts the
corresponding row into the card part of the window. The main window
also contains controls for searching of cards, and for adding and
deleting cards. There are several methods for searching: by keyword,
using the built-in query language, or using customizable standard
queries.

This chapter is intended as a user manual. For details on the
implementation of databases, and for advanced operations such as
building new applications with \grok, refer to the chapter ``Creating
and Editing Forms''.


\subsection Starting \grok

From the command line, grok can be started as {\tt grok} with no
arguments. This will bring up an empty card; a database must then
be chosen from the {\it Database} pulldown. The database to load
can be specified on the command line, such as {\tt grok~phone}.

The {\tt -t} and {\tt -T} options allows queries printed to stdout,
without starting the interactive graphical user interface. Queries
may use simple keyword lookups, or may use the query language:

\medskip
\cleartabs
\settabs \+ mmm & \cr
\+ & {\tt grok -t phone thomas} \cr
\+ & {\tt grok -t todo '($\{$\_status == "t"$\}$ \&\& $\{$\_assigned == user$\}$)'} \cr

For details on the query language used in the second example, refer
to the ``Expression Grammar'' chapter. The first example looks for
the given keyword; case distinctions are ignored. The author of the
application controls which columns of the database are searched for
keywords. Note the single quotes enclosing the query to protect
blanks, parentheses, and double quotes from the shell.

\grok\ supports the following command-line options:

{\tt grok} [{\it options}] [{\it database} ['{\it query}']]

\itmindent=1cm
\itm{\tt -h} print a short usage message listing the available options.

\itm{\tt -d} print the default X resources to stdout and exit. The
output can be appended to the local {\tt $\sim$/.Xdefaults} file or other
resource files, after changes to customize \grok's behavior.

\itm{\tt -v} print the version number of \grok.

\itm{\tt -t} Perform {\it query} and print the matching cards to
stdout. If {\it query} is missing, print all cards. The {\it database}
argument is mandatory for {\tt -t} and {\tt -T}.

\itm{\tt -T} Same as {\tt -t}, but omit the header line. This is
useful when the result is piped to other Unix utilities.

\itm{\tt -f} Do not fork on startup. This is mainly a debugging
tool; it prevents \grok\ from putting itself into the background.

\itm{\tt -r} Restricted {\tt grok}. The form editor is disabled to
prevent inexperienced users from inadvertently starting the user
interface builder (called the ``form editor'') and modifying the
current database format. The same effect can be achieved by linking
{\tt grok} to {\rm rgrok}; running {\tt rgrok} has the same effect
as running {\tt grok~-r}.


\subsection The Main Window

When \grok\ is started, it presents a four-part window: a search
area for entering keywords and query expressions, the summary, the
card, and a row of buttons for creating, deleting, and modifying
cards. There is also a menu bar with pulldown menus.

When \grok\ is started up without arguments, it is first necessary
to choose the database to display from the {\tt Database} pulldown.
This pulldown presents all files in the {\tt $\sim$/.grok} directory
that end with the extension {\tt .gf}, with the extension removed.
(If a new database is created, it is not necessary to choose a
database, see next chapter.) Sometimes, the Database pulldown
shows some databases more than once. The reason is usually that
the database is found in two different places or using different
paths; the duplicates can be eliminated by enabling the ``Don't
show duplicate databases'' in the preferences menu available
under the ``File'' pulldown.

The next step is choosing a {\it section} of the database. Not all
databases have section; if the {\tt Section} pulldown in the menu
bar is grayed out, this step can be omitted. \grok\ normally loads
its string table containing the cards from a file ending with the
extension {\tt .db}, usually with the same directory and root name
as the {\tt .gf} file. If this {\tt .db} file is a directory,
\grok\ recursively loads all files ending with {\tt .db} in this
directory, and combines them into one database in memory. Each file
becomes a {\it section}. By default, all sections are displayed
after loading a database, but the Section pulldown allows restricting
the summary listing to a single section (file). To create a new
section, choose ``New...'' in the Section pulldown; if the database
did not have sections until now all its cards are put into the new
section. Otherwise, the new section is created empty. There is no
way to delete sections, other than using a shell to delete the
file named {\it sectionname}{\tt .db} in the database directory.

The main window now displays all cards in the chosen database, or
section of the database if chosen, in the summary listing. To display
any card listed in the summary, press on this line. The card appears
in the bottom part of the window and can now be edited (unless the
database file was read-only, or the application author has restricted
write access). Text entry fields normally have a pink background;
read-only text fields have a gray background.

There is a special multi-line version of text entry field called a
{\it note}, which always has a gray background regardless of its
writable status. On some systems it is necessary to press in the
upper left corner of the inset area, or on already existing text
to get a cursor.

Below the card, there are buttons to skip to the next or previous
card, to create a new card ({\it New}), to duplicate the currently
displayed card, or to delete the currently displayed card. New
cards may be created with defaults specified by the application
designer. If the database has sections, there is an additional
buttons that moves the card into a different section.

\grok\ can optionally display a row of letter buttons below the
summary area that restrict the summary to display only cards whose
first text field begins with the selected letter. Case is not
distinguished; leading white space and punctuation is ignored.
The row of letter buttons can be enabled or disabled with the
``Enable search by initial letter'' mode in the preferences menu
that can be called with the ``Preferences'' choice in the ``File''
pulldown. The ``Letter search checks all words'' mode in the same
menu extends the letter search to check all words in the first
text field of each card, instead of just the first.


\subsection Searches and Queries

The Search text entry field near the top of the window allows entry
of a search string. Case is not significant. The entire string is
searched for; the number of blanks and punctuation is significant.
The search string is {\it not} a sequence of keywords. This type of
search is equivalent to what the Unix command {\tt fgrep~-i} does.

More sophisticated queries can be performed by entering a query
expression beginning with {\tt (} or {\tt $\{$}. For a description
of the syntax and the difference between parenthesized and braced
expressions, the the ``Expression Grammar'' chapter. To get a feel
for expressions, enable ``Show query search expressions'' in the
preferences menu and choose a canned query from the ``Query''
pulldown. The query expression will be shown in the Search text
field and can then be edited there.

The Query pulldown always begins with the ``All'' choice that puts
all cards in the database, or all cards in the current section if
one was selected with the Section pulldown, into the summary listing.
The application designer may predefine canned queries (using the
``Queries'' button in the form editor) that appear in the Query
pulldown.

If the ``Incremental searches and queries'' mode in the preferences
menu is enabled, each new search or query only checks the cards
already in the summary, thus narrowing the previous search or query.
To return to a complete listing, choose ``All'' in the Query pulldown.
If the incremental mode is disabled, all cards are checked.


\subsection Printing

The File pulldown has a ``Print...' choice that pops up the printing
menu. It allows selecting the cards to print, the output format, the
output quality, and the output device. Medium quality uses overstrike
Ascii to simulate boldfacing and underlining as supported by many
programs such as {\it more} and most printer drivers. It uses
character-backspace-character or underbar-backspace-character sequences
to highlight field names and header lines.

If ``Printer'' is chosen as output device, the printout is sent to
the Unix command line specified in the preferences menu. Typical
print spooler strings are ``lp'' (on System V) or ``lpr'' (on BSD
systems). It is also possible to enter shell commands such as
``cat~\>~/dev/tty''. The PostScript printer is specified separately
because a RIP program or special lp options may have to be specified;
this is currently not used because the ``PostScript'' quality choice
in the print menu is not yet implemented.


\subsection Miscellaneous

When a database is changed, the changes are not immediately written
to the database file (with the {\tt .db} extension). It is written
when ``Save'' or ``Quit'' in the File pulldown is chosen, or when
a new database is chosen from the Database pulldown. Under mwm-based
window managers, double-clicking the top left corner button in the
window decoration also saves, but there may be window managers that
do not support the necessary WM protocols for this. The status line
below the search text field displays ``(modified)'' if the database
has been changed but not written back.

Note that \grok\ does not attempt to sequence database accesses. It
does not protect databases against simultaneous accesses. Although
standard file locking is used during read and write operations
(which may or may not work across NFS), nobody stops two users from
reading the same file, then both modifying it, and writing it back;
one of the two changes will be lost.

A useful feature is the ``Current database'' choice in the Help
pulldown. It lists all known information about the current database,
including the names and paths of all loaded files and their sizes.

In case of trouble, it is {\bf strongly} recommended to read the
other help texts available under the Help pulldown, especially the
``Troubleshooting'' section. The Help pulldown will only work if
the {\tt grok.hlp} file is installed in the directory specified in 
the GLIB macro in the Makefile (Imakefile, or Makefile.alt), by
default /usr/local/lib.
